﻿<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML dir=ltr XMLNS:MSHelp = "http://msdn.microsoft.com/mshelp" xmlns:ddue = 
"http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink = 
"http://www.w3.org/1999/xlink" xmlns:tool = "http://www.microsoft.com/tooltip" 
XMLNS:[default] http://ddue.schemas.microsoft.com/authoring/2003/5 = 
"http://ddue.schemas.microsoft.com/authoring/2003/5"><HEAD><TITLE>MsgSecCertificate Sample</TITLE>
<META content="text/html; CHARSET=utf-8" http-equiv=Content-Type></META>
<META name=save content=history></META><LINK rel=stylesheet type=text/css 
href="../../../../../CommonFiles/Classic.css"></LINK>

<META name=GENERATOR content="MSHTML 8.00.6001.18783"></HEAD>
<BODY><INPUT id=userDataCache class=userDataStyle type=hidden></INPUT><INPUT 
id=hiddenScrollOffset type=hidden></INPUT><IMG 
style="WIDTH: 0px; DISPLAY: none; HEIGHT: 0px" id=dropDownImage 
src="../../../../../../Common/Html/drpdown.gif"></IMG><IMG 
style="WIDTH: 0px; DISPLAY: none; HEIGHT: 0px" id=dropDownHoverImage 
src="../../../../../../Common/Html/drpdown_orange.gif"></IMG><IMG 
style="WIDTH: 0px; DISPLAY: none; HEIGHT: 0px" id=copyImage 
src="../../../../../../Common/Html/copycode.gif"></IMG><IMG 
style="WIDTH: 0px; DISPLAY: none; HEIGHT: 0px" id=copyHoverImage 
src="../../../../../../Common/Html/copycodeHighlight.gif"></IMG>
<DIV id=header>
<TABLE id=topTable width="100%">
  <TBODY>
  <TR id=headerTableRow1>
    <TD align=left><SPAN id=runningHeaderText></SPAN></TD></TR>
  <TR id=headerTableRow2>
    <TD align=left><SPAN id=nsrTitle>MsgSecCertificate Sample</SPAN></TD></TR>
  <TR id=headerTableRow3>
    <TD></TD></TR></TBODY></TABLE>
</DIV>
<DIV id=mainSection>
<DIV id=mainBody>
<DIV id=allHistory class=saveHistory onload="loadAll()" 
onsave="saveAll()"></DIV>
<P>This sample demonstrates how to use the <B>WS2007HttpRelayBinding</B> binding 
with message security to secure end-to-end messages while still requiring clients 
to authenticate with the Service Bus. This allows the Service Bus to control client access 
    to the service endpoint while enabling 
encryption/signature protection on the message path.</P>
<H2 class=heading>Prerequisites</H2>
<DIV id=sectionSection0 class=section><content 
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
<P xmlns="">If you haven&#39;t already done so, read the release notes document that explains 
        how to sign up for a Windows Azure account and how to 
        configure your environment.</P>
</content></DIV>
<H2 class=heading>Echo Service</H2>
<DIV id=sectionSection1 class=section><content 
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
<P xmlns="">The service implements a simple contract with a single operation 
named <CODE>Echo</CODE>. The Echo service accepts a string and echoes it back.</P>
<DIV class=code xmlns=""><SPAN codeLanguage="CSharp">
<TABLE cellSpacing=0 cellPadding=0 width="100%">
  <TBODY>
  <TR>
    <TH>C#&nbsp;</TH>
    <TH><SPAN class=copyCode onfocusin=ChangeCopyCodeIcon(this) 
      onmouseover=ChangeCopyCodeIcon(this) onfocusout=ChangeCopyCodeIcon(this) 
      tabIndex=0 onkeypress=CopyCode_CheckKey(this) 
      onmouseout=ChangeCopyCodeIcon(this) onclick=CopyCode(this)></SPAN></TH></TR>
  <TR>
    <TD colSpan=2><PRE>[ServiceBehavior(Name = "EchoService", Namespace = "http://samples.microsoft.com/ServiceModel/Relay/")]
class EchoService : IEchoContract
{
    public string Echo(string text)
    {
        Console.WriteLine("Echoing: {0}", text);
        return text;            
    }
}</PRE></TD></TR></TBODY></TABLE></SPAN></DIV>
<P xmlns="">The service configuration contains one endpoint that refers to a 
<B>WS2007HttpRelayBinding</B> configuration, which uses message security with no 
    client credential. To secure the endpoint, the service is configured with the 
<CODE>certificateServiceBehavior</CODE> behavior. This behavior contains the service 
    credentials backed by the test certificate generated and installed using the 
    setup.bat script.</P>
<DIV class=code xmlns=""><SPAN codeLanguage="xml">
<TABLE cellSpacing=0 cellPadding=0 width="100%">
  <TBODY>
  <TR>
    <TH>Xml&nbsp;</TH>
    <TH><SPAN class=copyCode onfocusin=ChangeCopyCodeIcon(this) 
      nmouseover=ChangeCopyCodeIcon(this) onfocusout=ChangeCopyCodeIcon(this) 
      tabIndex=0 onkeypress=CopyCode_CheckKey(this) 
      onmouseout=ChangeCopyCodeIcon(this) onclick=CopyCode(this)></SPAN></TH></TR>
  <TR>
    <TD colSpan=2><PRE>
&lt;configuration&gt;
  &lt;system.serviceModel&gt;
    
    &lt;behaviors&gt;    
      &lt;endpointBehaviors&gt;
        &lt;behavior name="sharedSecretClientCredentials"&gt;
          &lt;transportClientEndpointBehavior credentialType="SharedSecret"&gt;
            &lt;clientCredentials&gt;
              &lt;sharedSecret issuerName=&quot;ISSUER_NAME" issuerSecret=&quot;ISSUER_SECRET" /&gt;
            &lt;/clientCredentials&gt;
          &lt;/transportClientEndpointBehavior&gt;
        &lt;/behavior&gt;
      &lt;/endpointBehaviors&gt;

      &lt;serviceBehaviors&gt;
        &lt;behavior name="certificateServiceBehavior"&gt;
          &lt;serviceCredentials&gt;
            &lt;serviceCertificate findValue="localhost" storeLocation="LocalMachine" storeName="My" x509FindType="FindBySubjectName" /&gt;
          &lt;/serviceCredentials&gt;
        &lt;/behavior&gt;
      &lt;/serviceBehaviors&gt;  
    &lt;/behaviors&gt;
    
    &lt;bindings&gt;
      &lt;!-- Application Binding --&gt;
      &lt;ws2007HttpRelayBinding&gt;
        &lt;binding name="messageSecurity"&gt;
          &lt;security mode="Message"&gt;
            &lt;message clientCredentialType="None"/&gt;
          &lt;/security&gt;
        &lt;/binding&gt;
      &lt;/ws2007HttpRelayBinding&gt;
    &lt;/bindings&gt;

    &lt;services&gt;
      &lt;!-- Application Service --&gt;
      &lt;service name="Microsoft.ServiceBus.Samples.EchoService" behaviorConfiguration="certificateServiceBehavior"&gt;
        &lt;endpoint name="ServiceBusEndpoint"
                  contract="Microsoft.ServiceBus.Samples.IEchoContract"
                  binding="ws2007HttpRelayBinding"
                  bindingConfiguration="messageSecurity"
                  behaviorConfiguration="sharedSecretClientCredentials" /&gt;
      &lt;/service&gt;
    &lt;/services&gt;

  &lt;/system.serviceModel&gt;
&lt;/configuration&gt;
</PRE></TD></TR></TBODY></TABLE></SPAN></DIV></content></DIV>
<H2 class=heading>Echo Service Client</H2>
<DIV id=sectionSection2 class=section><content 
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
<P xmlns="">The client is very similar to the client in the Echo sample, but 
differs in configuration and in how the channel factory is configured.</P>
<DIV class=code xmlns=""><SPAN codeLanguage="CSharp">
<TABLE cellSpacing=0 cellPadding=0 width="100%">
  <TBODY>
  <TR>
    <TH>C#&nbsp;</TH>
    <TH><SPAN class=copyCode onfocusin=ChangeCopyCodeIcon(this) 
      onmouseover=ChangeCopyCodeIcon(this) onfocusout=ChangeCopyCodeIcon(this) 
      tabIndex=0 onkeypress=CopyCode_CheckKey(this) 
      onmouseout=ChangeCopyCodeIcon(this) onclick=CopyCode(this)></SPAN></TH></TR>
  <TR>
    <TD colSpan=2><PRE>ChannelFactory&lt;IEchoChannel&gt; channelFactory = new ChannelFactory&lt;IEchoChannel&gt;("ServiceBusEndpoint", new EndpointAddress(serviceUri, EndpointIdentity.CreateDnsIdentity("localhost")));</PRE></TD></TR></TBODY></TABLE></SPAN></DIV>
<P xmlns="">Note that the <CODE>ChannelFactory</CODE> is constructed using an 
<CODE>EndpointAddress</CODE> that has an explicit "DNS" 
<CODE>EndpointIdentity</CODE>. The terminology may be a bit misleading here, 
because the identity is not directly related to DNS but rather to the 
certificate subject name. The identity name (<CODE>localhost</CODE> in this 
case) refers directly to the subject name of the certificate that is specified 
for the service identity in the <CODE>certificateServiceBehavior</CODE> behavior 
on the service-side. For an actual implementation, the service identity should 
be backed by a production certificate issued by a trusted CA and the 
<CODE>EndpointIdentity</CODE> must refer to its subject name. </P>
<P xmlns="">The client configuration mirrors the service configuration with a 
few exceptions. The client endpoints are configured with the 
<CODE>certificateEndpointBehavior</CODE> behavior, with 
<CODE>&lt;clientCredentials&gt;</CODE> settings that turn off certificate 
validation specifically for the test certificate that is being used here. For an 
actual implementation that uses a CA issued certificate, you should omit this 
override.</P>
<DIV class=code xmlns=""><SPAN codeLanguage="xml">
<TABLE cellSpacing=0 cellPadding=0 width="100%">
  <TBODY>
  <TR>
    <TH>Xml&nbsp;</TH>
    <TH><SPAN class=copyCode onfocusin=ChangeCopyCodeIcon(this) 
      onmouseover=ChangeCopyCodeIcon(this) onfocusout=ChangeCopyCodeIcon(this) 
      tabIndex=0 onkeypress=CopyCode_CheckKey(this) 
      onmouseout=ChangeCopyCodeIcon(this) onclick=CopyCode(this)></SPAN></TH></TR>
  <TR>
    <TD colSpan=2><PRE>
&lt;configuration&gt;
  &lt;system.serviceModel&gt;
    &lt;behaviors&gt;
      &lt;endpointBehaviors&gt;
        &lt;behavior name="certificateEndpointBehavior"&gt;
          &lt;clientCredentials&gt;
            &lt;serviceCertificate&gt;
              &lt;!-- The sample sets certificateValidationMode to None because it uses self-issued certificates.
                   Applications should typically set this value to ChainTrust (the default) or Custom if a customCertificateValidator is
                   specified. --&gt;
              &lt;authentication certificateValidationMode="None" /&gt;
            &lt;/serviceCertificate&gt;
          &lt;/clientCredentials&gt;
          &lt;transportClientEndpointBehavior credentialType="SharedSecret"&gt;
            &lt;clientCredentials&gt;
              &lt;sharedSecret issuerName=&quot;ISSUER_NAME" issuerSecret=&quot;ISSUER_SECRET" /&gt;
            &lt;/clientCredentials&gt;
          &lt;/transportClientEndpointBehavior&gt;
        &lt;/behavior&gt;
      &lt;/endpointBehaviors&gt;
    &lt;/behaviors&gt;
    
    &lt;bindings&gt;
      &lt;!-- Application Binding --&gt;
      &lt;ws2007HttpRelayBinding&gt;
        &lt;binding name="messageSecurity"&gt;
          &lt;security mode="Message"&gt;
            &lt;message clientCredentialType="None"/&gt;
          &lt;/security&gt;
        &lt;/binding&gt;
      &lt;/ws2007HttpRelayBinding&gt;
    &lt;/bindings&gt;

    &lt;client&gt;
      &lt;!-- Application Endpoint --&gt;
      &lt;endpoint name="ServiceBusEndpoint"
                contract="Microsoft.ServiceBus.Samples.IEchoContract"
                binding="ws2007HttpRelayBinding"
                bindingConfiguration="messageSecurity"
                behaviorConfiguration="certificateEndpointBehavior" /&gt;
    &lt;/client&gt;
  &lt;/system.serviceModel&gt;
&lt;/configuration&gt;
</PRE></TD></TR></TBODY></TABLE></SPAN></DIV></content></DIV>
<H2 class=heading>Running the Sample</H2>
<DIV id=sectionSection3 class=section><content 
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
<P xmlns="">To run the sample, first open App.config in both Serivce and Client 
    projects and replace the place-holders <b>ISSUER_NAME</b> and <b>ISSUER_SECRET</b> with the issuer name and secret you want to use.
  <br />Note that you may use the same values in both projects or alternately, you can set up multiple issuers and use different values for the Service and Client.<br />
</P>
    <P xmlns="">To generate and install the self-issued cerificate used by the sample, 
        run the setup.bat file included in the sample solution from a Visual Studio command line 
        window running with Administrator privileges.</P>
    <P xmlns="">After updating the configuration files, build the solution in Visual 
        Studio 2010 or from the command line, then run the two resulting executables. 
        Start the service first using an elevated command prompt, then run the client. 
        Both programs start by prompting you to type your service namespace.</P>
<P xmlns="">When the service and the client are running, you can start typing 
messages into the client application. These messages are echoed by the 
service.</P>
    <P xmlns="">After stopping the client and service you can run cleanup.bat from a 
        Visual Studio command line window with Administrator privileges to remove the sample 
        certificate from your computer&#39;s local store.</P>
<P xmlns=""><B>Expected Output – Client</B></P>
<DIV class=code xmlns=""><SPAN codeLanguage="other">
<TABLE cellSpacing=0 cellPadding=0 width="100%">
  <TBODY>
  <TR>
    <TD colSpan=2><PRE>Your Service Namespace: &lt;service namespace&gt; 
Enter text to echo (or [Enter] to exit): Hello, World!
Server echoed: Hello, World!</PRE></TD></TR></TBODY></TABLE></SPAN></DIV>
<P xmlns=""><B>Expected Output – Service</B></P>
<DIV class=code xmlns=""><SPAN codeLanguage="other">
<TABLE cellSpacing=0 cellPadding=0 width="100%">
  <TBODY>
  <TR>
    <TD colSpan=2><PRE>Service address: https://&lt;service namespace&gt;.servicebus.windows.net/EchoService/
Press [Enter] to exit
Echoing: Hello, World!</PRE></TD></TR></TBODY></TABLE></SPAN></DIV></content></DIV><!--[if gte IE 5]><tool:tip 
avoidmouse="false" element="languageFilterToolTip"></tool:tip><![endif]--></DIV>
<P>
<P xmlns="">
    <hr /> 
    Did you find this information useful?
    <a href="http://go.microsoft.com/fwlink/?LinkID=155664">
        Please send your suggestions and comments about the documentation.

    </a></P></DIV></BODY></HTML>
